/* vim: set sw=8 ts=8 sts=8 expandtab: */
#ifndef CMAID_CACHE_H
#define CMAID_CACHE_H

/**
 * @defgroup Cmaid_Cache The Cache Class
 * @ingroup Classes
 * @brief A cache to share objects
 *
 * The cache class provides an interface to reuse objects to reduce overall
 * memory usage. The cache is intended to be used for (large) constant arrays
 * or structures that are used in many place at the same time. Instead of having
 * an allocated copy of the object, the cache gives the opportunity to share
 * them, and to have only one copy of them. This can reduce the overall memory
 * usage. Keep in mind that this only works if the objects are not unique.
 *
 * Since the cache interface is inheriting from the container interface, you
 * can use all available container functions for it to.
 *
 * @note Only use the cmaid_iter_remove() if you really know what you are doing,
 *       because it will remove the object completely from the cache.
 */
/**
 * @brief Type definition of the Cache Class
 * @ingroup Cmaid_Cache
 */
typedef Cmaid_Container Cmaid_Cache;

/**
 * @defgroup Cmaid_Cache_Interface The Cache Interface
 * @ingroup Cmaid_Cache
 *
 * You only have to deal with the interface structure directly, if you are
 * going to write an implementation of the interface. Else you can safely
 * ignore this.
 *
 * @{
 */
/** Type definition for the @em instance callback */
typedef void *(*Cmaid_Cache_Instance_Cb)(Cmaid_Cache *s, const void *data);
/** Type definition for the @em release callback */
typedef void  (*Cmaid_Cache_Release_Cb)(Cmaid_Cache *s, const void *data);

/** Type definition for the @em cache interface */
typedef struct Cmaid_Cache_Interface Cmaid_Cache_Interface;

/**
 * @brief The Cache Interface structure
 * The cache interface is inheriting from the container and thus must also
 * have interface functions for the container.
 */
struct Cmaid_Cache_Interface
{
        Cmaid_Container_Interface container_if; /**< the container interface*/
        Cmaid_Cache_Instance_Cb   instance;     /**< instance callback */
        Cmaid_Cache_Release_Cb    release;      /**< release callback */
};
/**
 * @}
 */

/**
 * @addtogroup Cmaid_Cache
 * @{
 */
CMAID_INLINE void *cmaid_cache_instance(Cmaid_Cache *s, const void *data);
CMAID_INLINE void  cmaid_cache_release(Cmaid_Cache *s, const void *data);
/**
 * @}
 */

#include <cmaid_cache_funcdef.h>

#endif
